This file is made especially for the
person who runs a league using the
ESMS engine: the administrator. Before 
reading this document, it is vital to 
read the ESMS help file, and recommended 
to read numhelp.txt as well. It is also
highly recommended to ask me if you see
something you don't fully understand.


1 GENERAL INFORMATION
---------------------

1.1 The ESMS "basic package" includes 5 executable
programs and a few data files. First of all, you
have to unzip the files and preferably place
them in the same directory/folder. A descriptive
explanation about each file is included in this
document in section 2.

1.2 The "basic package" itself is not enough to run
a match in ESMS. Two team-sheet/lineup files must
be present: these files are sent to the administrator
by the managers who play in that match. The lineups
must be named "home.txt" and "away.txt". The rosters
of the involved teams must be present in the same
directory with the game-running program and the 
team sheets. It is very important to have a backup of
all roster files before each league round.

1.3 Make sure you read the 3rd section of this file,
which contains the limits of the ESMS program.


2 DETAILS ON FILES USED BY ESMS
-------------------------------

1.0 This sections deals with the various files
included in the ESMS package, and files which
are used/created by them. This information is very
important. Make sure you read it until you fully
understand all its aspects. Section 4 includes a
detailed example which guides you through running
a full round of games with ESMS with all the
necessary updates.

1.1 league.dat - This is the data file for a league,
and is used by most ESMS tools. Contents:

Home_Bonus: The home bonus in shot probability to
the home team. Standard is 200

DP_for_Yellow: The amount of disciplinary points
for a yellow card. Standard is 4

DP_for_Red: The amount of disciplinary points
for a red card. Standard is 10

Suspension_margin: The suspension margin specifies
the number of DP's a players gets before getting
suspended. If the margin is set to N, than after
a player reaches N DP, he is suspended to one game,
when he reached 2N DP he is suspended for 2 games
and so on. Standard is 10 

Abilities:

AB_Goal: Bonus for scoring a goal. Added to SAb

AB_Assist: Bonus for an assist. Added to PAb

AB_Ktk: Bonus for tackles. Added to TAb

AB_Kps: Bonus for passes. Added to PAb

AB_Sht_On: Bonus for shots on target. Added to SAb

AB_Sht_Off: Bonus for shots off targer. Added to SAb

AB_Sav: Bonus for saves. Added to KAb

AB_Concede: Bonus for conceded goals. Added to KAb, should
be normally specified negative.

AB_Yellow, AB_Red: Bonuses for Yellow & Red cards. These
are usually specified negative and are added to all
abilities except KAb for field players, or only KAb for
Goalkeepers. Note: a GK is a player whose St skill is
the highest.

AB_Defeat_Random: 2 players are chosen in random and 
given this (usually negative) bonus when their team
loses. Added to all abilities except KAb for field players, 
or only KAb for Goalkeepers.

AB_Victory_Random: 2 players are chosen in random and
given this (usually positive) bonus then their team
wins. Added to all abilities except KAb for field players, 
or only KAb for Goalkeepers.

AB_Clean_Sheet: When a team ends the game with a clean
sheet (no goals conceded), the GK (must have played 
at least 45 minutes) is awarded this (usually positive)
bonus, which is added to his KAb. Also, a defender is
chosen in random and is awarded this bonus to his TAb.


Abbrevations: 
Used by the updating programs when generating
the results and reports. Place here the abbrevated team names 
and what they mean, and the program will use them in the results
file (which will be discussed later).
For example,
mad = Real_Madrid
tot = Tottenham_Hotspur
(There mustn't be spaces inside a team name, use '_' instead,
ESMS will substitute '_'s for spaces when needed)

Note: The standards of the league.dat file were made using
various considerations and are good enough to run a 
successful league. However, if you feel that the needs
of your league are different, you may change them as 
you wish.


1.2 esms.exe - The most important program of the package: this
is the game running engine. This program uses the following
files as input: home.txt, away.txt (team sheets), two roster 
files (of the teams involved in the match), and league.dat. 
It creates the following files: teamname1_teamname2.txt 
(commentary file), teamname1_teamname2.stt (stats file for
use of the updating program) and will add a line to a file
named stats.dir (which is discussed below in this section).

1.2.1 esms.exe will also create a file called reports.txt
(it needs to be created only once, with the first
game, all the other games' reports will be added
to it automatically) which includes the score with
teams' full names (full names will be created only
if they are specified in the "Abbrevations:" section
in league.dat) and the list of scorers in the
game (with the minute on which they scored). This file is not
used by the other ESMS utilities. It is, however, used to
be sent to all the league managers, announcing the latest
scores in brief.

1.2.2 Sometimes there is need to run a decisive penalty 
shootout in a soccer game. It usually happens in cup games, 
when teams have equal score after one game, or after a two-leg
encounter. 
In order to run a penalty shootout after a game, all you 
have to do is to add the following line to the league.dat file:

Cup = 1

If this line appears in league.dat, after the game, the 
program promts you with the score of the game and asks whether 
you want to run a penalty shootout, like this:

Score: mil 1-0 tot
Would you like to run a penalty shootout ? (y/n)

If you choose 'y', the penalty shootout will added 
to the game commentary. It is important to note, 
that the shootout does not affect on any stats of 
the game. The result of the game itself (w/o the
penalty shootout results) will be 
added to results.txt and reports.txt, and no ability 
points are affected. 
How are the penalty takers chosen ? 
The program just chooses the players with the best
shooting skill from both teams, and they take the penalty
kicks.


1.3 stats.dir - This file contains the names of the stats
files that need to be included in the update. Each time
esms.exe runs a match, it will add the name of the stats
file to stats.dir and the updating program will then read
it line by line and update all the needed rosters with
the statistics. Note: After you run a round (a weekend of
games or whatever it called) be sure to delete stats.dir
so the stats won't be used again in the next round. (the
main program will create it again when running a new game).

1.4 teams.dir - This file contains a list of the teams (their
roster files) participating in the league. The names are the
roster names with extension: 
bar.txt
juv.txt
:
:
etc.
This file is used by some of the updating tools. You just 
have to create it once, list in it all the teams participating
and don't have to modify it throughout the season. 
Important: The roster files themselves must be present in
the same directory with teams.dir and with the updating tool
you are currently using.

1.5 updtr.exe - This is the most important updating tool in
the package of esms. It updated the roster files of the teams
using the stats files created by esms.exe
updtr has several updating options. The main one is explanied
here, the others are explained in the next paragraph.
The program opens the file stats.dir, and reads it line after
line, each time reading a name of a stats file. It opens that
stats file (make sure all the files are in the same directory)
and the rosters of the two teams participating in that game,
and makes all the necessary updates (adds minutes played, goals
scored, calculates the total ability) and saves the roster files.
Than, it moves to the next stats file listed in stats.dir and
makes the same updates. A whole round of games can be updated
to the rosters with a single click on updtr.exe, just make
sure all the stats files and the rosters are in the same directory
with updtr.exe and stats.dir
The updater not only updates the roster files, but also creates
4 information files on the round: injury.txt, suspend.txt, 
results.txt and skillch.txt. These files are made especially
to be sent to the participants of the league. More information
on them below.

1.6 The updater updtr.exe determines the injuries and suspensions 
of players from the stats files and adds the info to the roster 
files. But it doens't know when the injury or a suspension of a player 
ended. As you know, in ESMS, a player's injury period is
measured in weeks and suspension period is measured in games.
However, a "week" is not a very precise definition. If you
run a round of your league every day, then this "weeks is
one day, if you run it once a month, "week" is month. When
a "week" in your league passes, you should run the updtr.exe
program again, instruction it to "Decrease injuries". It will 
decrease the injury period of all the injured players in teams 
listed in teams.dir by one. If the injury period of a player 
became zero (thus, he has came back from the injury) after the 
update, the program will add a line to injury.txt indicating 
that (more on this in the next paragraph). 
The "Decrease suspensions" program does the same, but with suspensions. 
You should run it after each round of games in your league. It
does exactly the same like the injuries option, just with suspensions.


Note: The following 3 files are made by updtr.exe just for
information ! You can delete them or ingore them, ESMS doesn't
have any use in them. But, they contain useful information
on the round of games that the managers in your league might be
interested to know. Also note that if you want do supply information
for the last round of league games only, you should delete these
files before each weekly update. New files with the updated information
will be created by the program

1.6 injury.txt - This file contains the information on new injuries
and on expiring injuries. Each line contains information
about a player, the team he is playing in, and for how many
weeks he is injured, or returned from injury. Example:
R_Carlos (mad) is injured for 16 weeks
A_Del_Piero (juv) is coming back from injury
A_Cruz (mil) is injured for 1 week
etc.

1.7 suspend.txt - Contains the information on suspensions 
started and ended. For example:
N_Lennon (lei) is coming back from suspension
Giovanni (bar) is suspended for 1 game
F_Barthez (mon) is suspended for 2 games
etx.

1.8 skillch.txt - Contains the information on skill changes 
occured (added by updtr.exe). For example:
L_Thuram (par) Tk increases
Ronaldo (int) Ps decreases
A_Peruzzi (juv) St increases
etc.

1.9 results.txt - Contains all the results from the last round
(each time updtr.exe processes a stats file, it adds a line 
to results.txt with the result of the game). This file is made 
for information and for the use of the table updating program 
(read next paragraph for more imformation). For example:
Monaco 2 - 2 Barcelona
Juventus 3 - 1 Grasshoppers
Dynamo_Moscow 0 - 1 Bayern_Munich
Liverpool 1 - 1 Chelsea
etc.
Note: When updtr.exe adds results to results.txt, it uses
the abbrevations of team names in league.dat

1.10 table.txt - This file contains the updated league table,
and is used by the table updating program. It contains the
following headers:
Pl - Place (position in the table)   
Team - Team name                   
P - Games Played
W - Won
D - Drawn
L - Lost
GF - Goals For 
GA - Goals Against 
GD - Goal Difference
Pts - Points
Note: The table can hold up to 50 teams.
There is a template table present in the package of @esms, you
can use it, just change the team names.


1.11 lgtable.exe - Uses table.txt and results.txt to update
the table with the latest results. The points are calculated
by 3 points for a victory, 1 points for draw, 0 points for
a defeat.

1.12 tsc.exe - Team Sheet Creator. If some of the managers 
didn't submit their team sheets to the administrator,
and the league round still should be run, then tsc.exe is
used. This program creates a valid team sheet of a certain
team (specified by the administrator). How to use it:
Run tsc.exe. The program will ask for a roster name as
an input. Enter the roster name (for example juv), make
sure it is present in the same directory first. On success,
tsc.exe will create a file called [rostername]sht.txt
(in our example: juvsht.txt). 
A simple 4-4-2 formation of players will be created, using
the Normal tactic. Just change the file name to home.txt 
or away.txt as needed and you can run the game.

1.13 leaders.exe - This program calculates the 20 league 
leaders in 4 different categories:
Leading league scorers: scorers.txt
Leading league assisters: assistrs.txt
Leading league performers: performs.txt
League leaders in DP: dps.txt
While the first two leaders are pretty natural, some notes
on the other two are needed... Leading DP's will list the
players with the worst discipline - most DP.
Leading performers will list the players with the best
performance in the league. The performance formula is based
on the players' stats:
goals*9 + shots + tackles*6 + saves*3 + assists*7 + keypasses*4 - dp's
This program will read teams.dir and calculate the leaders
based on the teams listed there. All 4 files are created
when leaders.exe is run. 
Note: leaders.exe is just an additional program, which
adds some taste and competition between the players. A 
league can run without it.


3 SOME IMPORTANT LIMITS ON THE ESMS PROGRAM
-------------------------------------------

3.0 This section contains the maximum/minimum for various
numerical values and quantities in ESMS.

3.1 Rosters:
Roster names: Preferred and very much recommended to use
3 letter abbrevations.
Maximum number of players: 50
Minimal number of players: Don't really have any defined
minimal value. However, a manager must have at least 16
valid (not injured/suspended) to put up a team for a game.
Longest player name: 13 characters

3.2 Team sheets:
Team sheet names: Must be one named "home.txt" and one
named "away.txt" for ESMS.exe. 
Players: 16 players must be listed. The first 11 will be
considered as the opening squad, the last 5 as the subs.
Goalkeeper: The first player in the team list MUST be 
a goalkeeper.
Conditionals: There are 3 types of conditionals: tactic
change, player's position change and substitution. Up to
10 conditionals of each type can be listed. Note that 
there will be no more than 3 substitutions made during 
the game.

3.3 League table:
Maximum teams: 50
Minimum teams: 2



4 A COMPLETE EXAMPLE
--------------------

This is a complete example of running a round of a league
using ESMS. The sample league consists of only 2 teams,
but the principles are the same and it's easy to extend
the practice to any amount of teams. The same requires
a few files which can be found in the "sample" directory.

The sample files are: 2 rosters - bar.txt and laz.txt 
(the teams are Barcelona and Lazio), 2 teamsheets - barsht.txt 
and lazsht.txt and a template table.txt file.

Extract the ESMS package into some directory and copy
the sample files into it (the files must be located in the
same directory with all the executables, league.dat and
language.dat).

Open the template table.txt, delete everything but the first two
teams. Change their names to Barcelona and Lazio.

The table file should now look like this:

Pl   Team                   P    W   D   L    GF   GA   GD   Pts
----------------------------------------------------------------
1    Barcelona              0    0   0   0     0    0    0     0
2    Lazio                  0    0   0   0     0    0    0     0

Now, create a file named teams.dir and add the roster names to it. 
teams.dir should look like this:

bar.txt
laz.txt

Open the league.dat file. If you've read this whole help file
(admhelp.txt) thoroughly you should know what everything in
league.dat means. You'll now add 2 abbreviations to the end
of league.dat (place them below the "Abbrevations:" line):

bar = Barcelona
laz = Lazio

The bottom part of league.dat should now look like this:

Abbrevations:
bar = Barcelona
laz = Lazio

You're now ready to run your first ESMS game.

If you recall, teamsheets for both teams were supplied in the
sample directory. 
For our example, let Lazio be the home team. Rename lazsht.txt
to home.txt, and rename barsht.txt to away.txt

Run esms.exe
"Game was finished successfully" is printed on the screen,
meaning esms.exe successfully ran a game between our 2
teams.

Look at the directory, there were 4 new files created:
laz_bar.stt - stats file used by the updating programs
laz_bar.txt - the game commentary
reports.txt - reports of all games run (only one in our case)
stats.dir - list of all stats files (only one in our case)

You don't need laz_bar.txt for the updates, it can be sent
to the managers of Lazio and Barcelona if you're running
a real league. Same with reports.txt, which is an informative
file meant to be sent to the mailing list of the league or
to all the managers, informing them of all the round results
in brief.

Now, you can upate the game stats in the team rosters. 
Run updtr.exe and choose the "Update rosters with latest 
game stats" option (the other options won't be used in
this single round sample, but you will use them to run
a normal league).
Some new files were created, but first of all look at the
rosters and note that they have been updated with the
game stats of the game you ran. You can check some of
the stats by looking what each player did in the commentary
and compare it to the updated roster file.

The new files created are injury.txt, suspend.txt, results.txt
and skillch.txt, you already know what should be included 
in them (note that if no injuries/suspensions/skill changes
occurred in the game you ran, injury.txt, suspend.txt and skillch.txt
will be empty). 
Look at the file named results.txt, the result of the game
is included there. Note that the teams in it have their full
name, because the updater used the abbrevations  set in league.dat
Of the 4 created files, only results.txt is used for further
updates. The other 3 files should be sent to the managers
to inform them of the lattest developments.

You can now update the league table.
Just make sure that lgtable.exe, results.txt and
table.txt are all in the same directory and run
lgtable.exe
You can now see that table.txt was updated with
the game result.

Congrats ! You've just run your first round of a league with
ESMS. Not all of the tools were used, only the most important
ones. I'm sure you won't have a problem running the other
tools on your own. Naturally, you can always turn to me
with questions if you run into problems.

Note: Always remember to make backups of the rosters
and other important files (league.dat, table.txt, teams.dir)
after each round.

-----------------------------------
Eli Bendersky: spur@cyberdude.com

